Inside Macintosh: QuickDraw GX Graphics /

Chapter 2 - Geometric Shapes / Geometric Shapes Reference

Functions / Editing Shape Geometries

GXGetShapeParts

You can use the GXGetShapeParts function to extract a copy of a specified range of geometric points from the geometry of one shape and encapsulate it in another shape.

gxShape GXGetShapeParts(gxShape source, long index, long count, 
                        gxShape destination);

source

A reference to the shape containing the desired geometric points.

index

The geometry index of the first geometric point to copy.

count

The number of geometric points to copy. You may provide the gxSelectToEnd constant for this parameter.

destination

A reference to the shape to encapsulate the copied geometry information.

function result

A copy of the reference returned in the destination parameter.

DESCRIPTION

The GXGetShapeParts function copies geometry information from the source shape into the destination shape. This function copies all of the geometry information starting with the geometric point indicated by the index parameter and continuing for as many geometric points as indicated by the count parameter. This function copies the values of the indicated geometric points and retains the information about contour breaks from the original geometry, as well as the information about which points are on curve and which are off curve. As a convenience, the function returns as its function result a reference to the destination shape.

Both the index and the count parameters must be greater than 0, although you can provide the gxSelectToEnd constant for the count parameter, which indicates that you want a copy of all the geometric points (starting with the geometric point indicated by the index parameter) in the source shape's geometry.

You may pass nil for the destination parameter. In this case, the function creates a new shape of the appropriate type and encapsulates the extracted geometry information in this new shape.

If the source shape is one of the geometric shape types, this function returns a geometric shape type, as described in the following table:

Shape type	Action taken
empty	Returns an empty shape
full	Returns a full shape
point	Returns a point shape
line	Returns a point or a line shape, depending on the number of geometric points copied
curve	Returns a point, line, or curve shape, depending on the number of geometric points copied
rectangle	Returns a point or a rectangle shape, depending on the number of geometric points copied
polygon	Always returns a polygon shape, even if only one or two geometric points are copied
path	Always returns a path shape, even if only one, two, or three geometric points are copied

If you provide a source shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Posts shape_operator_may_not_be_a_bitmap error
picture	Returns the number of picture items
text	Returns the number of glyphs
glyph	Returns the number of glyphs
layout	Returns the byte length of the text

SPECIAL CONSIDERATIONS

If you pass nil for the destination parameter and no error results, the GXGetShapeParts function creates a shape; you are responsible for disposing of this shape when you no longer need it. See Inside Macintosh: QuickDraw GX Objects for information about creating and disposing of objects.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
index_is_less_than_one	(debugging version)
count_is_less_than_one	(debugging version)
Warnings
shape_operator_may_not_be_a_bitmap
index_out_of_range
count_out_of_range

SEE ALSO

For information about other functions that allow you to extract information from shape geometries, see the description of the GXGetShapePoints function on page 2-140, the description of the GXGetPolygonParts function on page 2-144, and the description of the GXGetPathParts function on page 2-148.

To replace parts of a shape's geometry, use the GXSetShapeParts function, which is described in the next section.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help